Skip to content

fix(bundler): resolve built-in step types when checking bundle component references - #3885

Open
jawwad-ali wants to merge 2 commits into
github:mainfrom
jawwad-ali:fix/bundler-builtin-step-references
Open

fix(bundler): resolve built-in step types when checking bundle component references#3885
jawwad-ali wants to merge 2 commits into
github:mainfrom
jawwad-ali:fix/bundler-builtin-step-references

Conversation

@jawwad-ali

Copy link
Copy Markdown
Contributor

Problem

_resolved_locally in src/specify_cli/bundler/services/references.py gives three of the four component kinds a "is it bundled with Spec Kit?" check before the installed-in-project check. steps is the exception:

kind bundled check installed check
presets _locate_bundled_preset PresetManager(root).get_pack
extensions _locate_bundled_extension ExtensionManager(root).registry.is_installed
workflows _locate_bundled_workflow WorkflowRegistry(root).is_installed
steps none StepRegistry(root).is_installed

StepRegistry tracks community step types installed under .specify/workflows/steps/. Spec Kit ships 11 step types as built-ins registered in STEP_REGISTRY.

Reproduction on current main (81bf741)

built-in step types (11): ['command', 'do-while', 'fan-in', 'fan-out', 'gate',
                           'if', 'init', 'prompt', 'shell', 'switch', 'while']

_resolved_locally for a BUILT-IN step type:
  steps/shell      -> False
  steps/gate       -> False
  steps/command    -> False
  steps/if         -> False

So a bundle that declares a dependency on any built-in step type is reported as an unresolved reference — a hard error with --allow-network, a warning offline. Those are exactly the step types a bundle is most likely to depend on.

Fix

There is no _locate_bundled_step to mirror, because step types are not an on-disk asset directory — they are registered in code. STEP_REGISTRY is the bundled-with-Spec-Kit check for this kind, and it is what specify workflow step info already reports as "built-in":

from ...workflows import STEP_REGISTRY
...
if component.id in STEP_REGISTRY:
    return True
return StepRegistry(root).is_installed(component.id)

The import stays lazy and inside the function, matching every other branch. Importing specify_cli.workflows runs _register_builtin_steps(), exactly as workflow step info relies on.

No breaking change. This only makes previously-unresolvable ids resolve. A second new test pins that an unknown step id (no-such-step-type) still errors, so the guard has not made everything resolve.

Verification

  • Fail-before / pass-after: test_builtin_step_type_resolves fails on unpatched src and passes with the fix. File: 1 failed → 5 passed.
  • Scoped regression over tests/unit: failure set identical to the clean-main baseline captured on 81bf741 (2 pre-existing in scope).
  • uvx ruff@0.15.0 check src tests → clean

Tests sit beside test_bundled_extension_resolves, the exact sibling assertion for the bundled-with-Spec-Kit case.


Written with assistance from Claude Code. Bug found, reproduced, and verified by me on current main.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Fixes bundle validation for built-in workflow step references.

Changes:

  • Resolves step IDs found in STEP_REGISTRY.
  • Adds built-in and unknown-step regression tests.
  • Blocking issue: STEP_REGISTRY also contains custom steps loaded from other projects.
Show a summary per file
File Description
src/specify_cli/bundler/services/references.py Adds step registry resolution.
tests/unit/test_bundler_references.py Tests built-in and unknown step references.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

  • Files reviewed: 2/2 changed files
  • Comments generated: 1
  • Review effort level: Balanced

Comment thread src/specify_cli/bundler/services/references.py Outdated
jawwad-ali and others added 2 commits July 31, 2026 22:39
…nces

`_resolved_locally` gives three of the four component kinds a
"is it bundled with Spec Kit?" check before the installed-in-project one:

  presets    -> _locate_bundled_preset   or PresetManager.get_pack
  extensions -> _locate_bundled_extension or ExtensionManager...is_installed
  workflows  -> _locate_bundled_workflow  or WorkflowRegistry.is_installed
  steps      -> StepRegistry.is_installed          <-- no bundled check

`StepRegistry` tracks *community* step types installed under
`.specify/workflows/steps/`. Spec Kit ships 11 step types as built-ins
registered in `STEP_REGISTRY`, so every one of them looked unresolved:

  steps/shell   -> False
  steps/gate    -> False
  steps/command -> False
  steps/if      -> False

A bundle declaring a dependency on any built-in step type was therefore
reported as an unresolved reference — an error online, a warning offline.

There is no `_locate_bundled_step` to mirror, because step types are not
an on-disk asset directory; `STEP_REGISTRY` is the equivalent check, and
is what `specify workflow step info` reports as "built-in".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…egistry

Review catch: `STEP_REGISTRY` is not limited to bundled steps.
`load_custom_steps` adds project-installed ids to that process-global
mapping and never removes them, so in a long-lived process a community step
loaded while working on project A would be accepted as "bundled" when
validating a bundle for project B — before B's own StepRegistry is
consulted.

Snapshot the shipped ids into `BUILTIN_STEP_TYPES` immediately after
`_register_builtin_steps()`, before `load_custom_steps` is even defined,
and check that frozenset instead.

Verified: with the check on STEP_REGISTRY the new cross-project test fails
(a leaked community id resolves as bundled); with BUILTIN_STEP_TYPES it
passes. 1 failed, 5 passed -> 6 passed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@jawwad-ali
jawwad-ali force-pushed the fix/bundler-builtin-step-references branch from d99b4bb to bb16911 Compare July 31, 2026 17:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants